Why use a screen saver?
=======================
Because it's pretty, that's why. It also helps to prolong the life of your
monitor by preventing stationary images from 'burning in' on the screen.

What does Blackout do?
======================
Blackout is a sub-program of Black Hole II. If you have the Screen Saver
enabled, Black Hole will watch you, very closely. If you leave your computer
unattended for a certain length of time Black Hole will run Blackout.
Blackout will then entertain the empty room by displaying one of several
pretty patterns or silly effects until you come back. By moving the mouse or
pressing a key you will stop Blackout and the world will return to normal.

[234]
There is also a bit of program which checks the serial port, and if any
data comes in or goes out of the serial port, Blackout will quit. Serial
port activity will also prevent Blackout from cutting in. I hope. The trouble
is that although I put the code in there I don't use my serial port for
anything so I can't test it. Such is life.

[1234]
Configuring Blackout
====================

You can enable Blackout simply by selecting the 'Screen Saver Enabled' button
at the botom of the Black Hole Configuation window. But there is more to it
than that. You also have a choice of pretty pattern and a variable delay
before it cuts in. You can set these by clicking on the 'Configure..." button
in the Blackout section of the Black Hole configuration window.

At the top is a box telling you what the currently selected screen saver is.
You can choose a new one by clicking on the arrow icon next to this box and
selecting a screen saver name from the menu that appears. Note that these are
not very helpfully named. This is intentional, to make you think.

Next to the 'Saver' box is a white box labelled 'Delay (mins)'. This is the
time (in minutes) of inactivity on your behalf before Blackout will be
started. You can type any number in here, including decimals.

[1]
The rest of it is far too complicated for you. Just be thankful you've read
this far without your brain exploding.

[234]
Below this lot is another white box labelled 'Parameters'. This is where
the fun starts. Most of the screen savers have user-configurable parameters,
such as Speed, Number of dead bodies, that sort of thing. In this box the
default parameters will appear. The parameters are simply a collecion of
numbers and/or words that have meaning to that particular screen saver.
Thus for the saver 'Stars', the default parameters might be 40,30.
This is not very meaningful to the average user and so the box below this
contains a description of what the parameters mean.

You can change the parameters to be anything you like, provided you're
sensible. But do NOT put any spaces between the values, only commas (you
MUST use commas).

[1234]
The other bits.
===============

If you want to see what the screen saver will look like, click on the 'Demo'
button. This will run Blackout so you can see what it looks like and what
difference changing the parameters has made. The demo will continue until
you move the mouse or press a key.

To forget all your changes and revert to what the options were before you
started Configuring, click Cancel.

To save your changes permanently to disc so that they become the defaults
next time Blackout is run, click Save.

To quit Configuration and update the settings without making the change
permanent, click OK.

Sleep Corner.
=============

When the screen saver is enabled, you can force it to cut it by putting the
mouse in the bottom left corner of the screen for a few seconds.

Passwords.
==========

A subtle security feature. Blackout allows you to protect your computer
from prying eyes by not allowing you to return to the desktop without
entering a password. What will happen if you have a password set is that
when someone attempts to stop Blackout (by moving the mouse, etc.) a window
will pop open asking for the password. If the wrong password is entered,
Blackout will not stop and so your desktop will remain invisible.

To set a password, click the Change Password... button. This opens a window
which will ask you to type your new password. The password will display
as a string of *s to prevent anyone watching from seeing it. Press Return or
click OK. You will then be asked to retype the password for confirmation.

If you already have a password set and you want to change it you must first
enter the old password.

To clear the password so that the password feature does not operate, simply
press Return without entering any text when asked for the New Password.

User-Defined Screensavers
=========================

If you have a knowledge of BASIC you can write your own screen saver to
be included in BlackOut.
[4]
This will be explained later.
[1234]

Notes on some of the Screen Savers included
===========================================

Blocks: Turns the desktop into one of those sliding block puzzles. Because of
        the way this is written (sloppily) you can only make the speed 1, 2
        or 4.
        
Circles: Is a trifle dull.

Crumble: Subtly destroys your screen from the top down.

Hypno: Is like circles but better.

Hypno2: Is a bit similar.

Lines: Is wierd and is only there because it is.

Melt: Melts your screen. Unlike other screen savers of this type, Melt
      actually looks realistic. Sometimes.
      
Message: Scrolls a message across the screen in your choice of outline font.

Sprites: A sprite of your choice can be made to fly towards you in great
         numbers.
[4]
         You can use any sprite from the WIMP sprite pool.
[3]
         You can use any standard desktop sprite (i.e. one that is in the
         WIMP sprite pool). To set up a sprite, just create a sprite file
         then *IconSprites that sprite file.
[12]
         You can use any of the sprites that the desktop uses - i.e. any of
         the application sprites (e.g. the sprite !Blakhole2 to use the
         Black Hole sprite, !Draw to use the draw sprite, etc.)
[2]
         You can add your own sprite to the desktop sprite pool by creating
         it using Paint, saving the sprite file somewhere, then issuing the
         command (from the command line (press f12))
         *IconSprites <file>
         where <file> is the full pathname of your sprite file. You will have
         to do this every time before you start the computer up. The easiest
         way is to add the *Iconsprites command to your desktop boot file.
[1234]

Squares: Is a bit like circles, only with Squares.

Squares2: Is a bit like Squares.

Stars: Fly through space - the stars fly towards you.
[4]
       This one's written in (not very efficient) ARM code, so it's quite
       quick.
[1234]
         
Swirl: Is a variation on Squares and Squares2

Public Domain Notice:
=====================

The Public Domain rules concerning Blackout are slightly different from the
rest of Black Hole.

Blackout is phase 5b of Fat German Production's now defunct plan for world
domination. It is released by courtesy of the Fat German in association
with the Great Green Gollywog, his minions, and his sister Ethel. It may be
freely copied and used, as long as the following conditions are met:

a) That this notice is distributed unchanged with every copy.
b) That the application is supplied unmodified. Extra screen savers may be
   inculded by anyone who wishes to, but all other parts of the program are
   to be regarded as sacred.
c) No charge is made for the distribution. Public domain libraries may make
   a small charge to cover distribution costs. It is highly unethical, not
   to mention dishonest to make a charge for software which programmers
   have intended to be freely distributed, especially if none of that profit
   finds its way to the programmer.
d) Neither !BlackOut or !BlkOutCfg may be distributed separately from
   !BlakHole2.
e) Anyone who drives a Honda CRX must destroy it before I will allow them
   to use this program.

All copyright is reserved. You may not use any part of this application in
any project which is to be sold for profit without my express permission
in writing.

All code in the file 'BlackOut' is copyleft. You may use it in whatever way
you feel fit. Code in the directory 'Savers' is fit for butchering in all
manner of ways. You may steal any bits of code to use in your own savers
unless the author of the saver has specifically asked you not to by including
a REM statement to that effect at the start of his saver.

The program 'Blackout' may not be distributed in modified form without my
permisson.

[4]
If you can think if any ways to improve the code then please do so,
and let me know.

        Information for people who want to write their own screensavers.
        ================================================================
        
Hopefully this won't get too technical, but bear with me 'cos it's late and
I've run out of coffee.

The intention with Blackout was to write a screensaver which could be
easily extended by the addition of new bits. The other intention was that
the new bits should be easy to write so that people with little in-depth
knowledge of the WIMP and graphics (such as me) could write their own savers.

To write a screen saver for Blackout you will need the following:
a) A BASIC editor (preferably !Zap, because it's great).
b) Part of a brain. Preferably yours, but you can borrow one if necessary.
c) An idea.

Generally, I find that part c is the hardest. The evidence for this comes
from the quality of the savers I supply as standard.

The best way to see how to do it is to look at some of the predefined savers,
but a few notes might help.

Format
======

A screen saver for Blackout is a framgent of a BASIC program. The main
Blackout program uses BASIC's OVERLAY command to merge the two sections.
A screen saver must contain the following two DEFPROCs:

DEFPROCinitsaver - to initialise the variables used in the screen saver and,
                   if necessary, clear the screen. You could also assemble
                   a machine code routine, but you will need to DIM your
                   own memory for this (or use PROCmemory - see below).
                   'Stars' uses a machine code routine, and simply sets this
                   up by using a DIM statement in PROCinitsaver to allocate
                   some memory for the code.
                   
DEFPROCupdatesaver - to provide one 'step' in the animation of the saver.
                     This must be written so that it ENDPROCs after not too
                     long so that the WIMP can carry on polling other
                     applications. For example, in the 'Stars' saver this
                     procedure erases the stars, updates their coordinates,
                     replots them, then returns.
                     
You can add as many other procedures as you like, provided they don't have
the same names as ones in the main program (see below). The same applies to
your own variables.

You don't have to worry about checking for key presses or mouse movements or
anything because the main program does that for you.

The saver must also contain three REM statements at the start of the file:

REM <Saver Name>
REM Parameters:Descr1,Descr2
REM Defaults:30,40

The first line is obvious. The second is the description string which appears
in the Configuration window. The third is the defaults used by the config.
program.

You can also put two further lines in:

REM Author:<author's name>
REM Description:<short description>

These will be displayed in the "Saver Information" box.

Your screen saver must be mode-independent. To help you in this, some
variables are supplied by the main program.

Supplied Variables
==================

The main blackout program sets up a number of variables which the saver can
use. These are:

   options$(0)-options$(10) contain each of the parameters as passed to
   blackout by the configuration program. In the above example options$(0)
   would be "30" and options$(1) would be "40". Note that all these are
   string variables.
   
   numcols% is the number of colours that the current screen mode supports.
   
   scrx%,scry% are the screen mode x and y size in OS units.
   
   xeigen%,yeigen% should be the number of OS units per pixel, but whenever
   I try it, they seem to be the number of OS units per pixel divided by 2.
   
   handle% : If you want to use an outline font you will need a variable to
   store the font handle from Font_FindFont. I recommend you use handle% for
   this because then Blackout will do a Font_LoseFont when it closes down.
   If you use your own variable the font will remain open (unless you edit
   Blackout, which I would rather you didn't).
   
Useful Procedures
=================

Some procedures are also supplied by the program which may be of general use:

  PROCblack - clears the screen to black. If you want to do this I suggest
  you use this procedure because it sets a flag which the main program uses.
  It's not very fast, but it works.
  
  FNreadvar - will read a system variable and return the result as a string.
  
  PROCmemory - is used to gain a large block of memory if, for instance, you
  want to set up a large user sprite area. The procedure takes one parameter,
  which is the amount of memory (in bytes) that you want. The variable
  rmablock% points to the start of this memory. The program uses 
  SYS"Wimp_SlotSize" to get the memory, but the variable is called rmablock%
  because I originally used the RMA. So there. This procedure will abort the
  program if the required memory cannot be grabbed.
  
Reserved Names
==============

Procedures in your fragment of program must not have the same names as ones
in the main program. The following PROC and FN names are reserved:

  PROCaskforpassword
  PROCblack
  PROCcheckpassword
  PROCinitwimp
  PROCloadwindows
  PROCmemory(bytes%)
  PROCmessage(woof%)
  PROCopenwindow
  PROCps(window,icon,s$)
  PROCquit
  PROCscrnxy
  PROCselic(bl%!0,bl%!4,bl%!8,bl%!12)
  PROCstupidity
  FNgaga(add%)
  FNlust(bl%!0,bl%!4)
  FNreadvar(var$)

The same applies to variables. The following variable names are reserved.

    bl% 				entry$
    black%				home$
    getlost%				opt$
    handle%				options$()
    indirect%  				overlay$()
    main%				pass$
    mx%					password$
    my%					saver$
    myid%
    mz%
    numcols%
    omx%
    omy%
    omz%
    p%
    password%
    passwordtimer%
    quit%
    reason%
    rmablock%
    rollocks%
    scrx%
    scry%
    time%
    valid%  
    windows%  
    wv%
    xeigen%
    yeigen%
    
Notes
=====

For hints and examples, look at the other savers. Most of them acheive some
pretty-looking results using just RECTANGE FILL ... TO .. 

When you've written your saver, save it in the directory "!Blackout.Savers".
